MSP-1 Specification

canonical

The canonical term defines the single, authoritative representation of a resource. It enables AI agents to resolve duplicates, consolidate signals, reduce ambiguity, and identify the definitive source for content.

Category: Document lifecycle, versioning & compliance

Status: Normative

Version: MSP-1.0.x

1. Purpose

Many web resources appear in multiple locations or formats. The MSP-1 canonical declaration resolves ambiguity by explicitly naming the authoritative primary representation AI systems should treat as the single source of truth.

2. Normative definition

A canonical declaration identifies one—and only one—resource instance as the official, primary version. All other instances should be treated as derivatives, mirrors, excerpts, or alternates.

A valid canonical declaration MUST:

Specify a stable canonical URL.
Be unique—no conflicting canonical declarations for the same resource.
Represent the version intended as the authoritative reference.

3. Required fields

An MSP-1 canonical object MUST include:

url — the canonical URL of the authoritative resource.

Recommended additions:

reason — why this version is canonical (e.g., “official source”).
scope — if canonical applies to a subset (e.g., a section or variant).
version — if canonical designation is version-bound.

4. AI interpretation rules

AI agents MUST treat the canonical URL as the authoritative representation when answering questions or consolidating metadata.
Content variants SHOULD inherit metadata from the canonical version unless they explicitly override it.
If multiple alleged canonicals exist, agents SHOULD flag the resource as ambiguous and down-rank confidence.
Canonical declarations SHOULD override heuristics (e.g., “first indexed”).

Canonical is not the same as authoritative or official; it designates the primary representation, not the trust level.

5. Relationship to related MSP-1 terms

revision — canonical may point to a specific revision.
version — canonical may apply at the version level.
provenance — defines the lineage of copies or derivatives relative to the canonical source.
trust — canonical status does not imply trust; it simply defines primacy.

6. Examples

Minimal canonical declaration:

{
  "canonical": {
    "url": "https://msp-1.org/spec/canonical/"
  }
}

Expanded example with reasoning and version context:

{
  "canonical": {
    "url": "https://photographyselect.com/lighting-guide/",
    "reason": "This is the officially maintained and updated version.",
    "version": "1.3.2",
    "scope": "full document"
  }
}

7. Conformance

A resource conforms to the MSP-1 canonical specification when:

Only one canonical declaration exists for the resource.
The canonical URL is stable, accessible, and properly formatted.
Derived versions link back (where possible) to the canonical source.