Projection Profiles

Profiles control payload visibility — they are a pure view layer over canonical enrichment state.

A profile never mutates orchestration, processing lifecycle, or the canonical enrichment registry. For the same underlying resource, FAST/STANDARD/FULL report identical completedStages, pendingStages, and enrichmentsPending. Only payload richness differs.

Profile Comparison

Aspect	FAST	STANDARD	FULL	EMBED
Latency	Minimal	Progressive	Deterministic	Minimal
HTTP Status	200	200 or 202	200	200
Diagnostics	Omitted	Omitted	Included	Omitted
Provider Data	Omitted	Included	Included	Included (Capabilities)
Generated Preview	Projection-hidden	Null or populated	Complete	Omitted
Provider-Native Preview	✅ Preserved	✅ Preserved	✅ Preserved	Omitted
Heavy Fields (e.g. playback.html)	Omitted	Included	Included	On-demand via expand

FAST Profile

Minimal projection optimized for low latency. Returns immediately with lightweight metadata.

curl -X POST https://api.urlmediainspector.dev/api/v1/inspect?profile=fast \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/GLTTI1NFHus?si=okdNMy6_p0VSqZJG"}'

FAST Projection Rules

• playback.html — omitted (heavy field)
• data.diagnostics — omitted
• data.providerData — omitted
• Generated preview (placeholder, palette) — projection-hidden
• Provider-native preview (e.g., YouTube thumbnail) — preserved

Key Behavior

FAST provider-native preview is not marked as hiddenFields. Only generated enrichments that require background processing are projection-hidden in FAST.

FAST Response — YouTube (Provider-Native Intelligence)

{
  "success": true,
  "responseSource": "fresh",
  "cached": false,
  "processing": {
    "status": "complete",
    "completion": 1,
    "enrichmentsPending": false,
    "completedStages": ["semantic", "mediaFormat", "oembed"],
    "pendingStages": []
  },
  "data": {
    "identity": {
      "url": "https://youtu.be/GLTTI1NFHus?si=...",
      "finalUrl": "https://youtu.be/GLTTI1NFHus?si=...",
      "canonicalUrl": "https://www.youtube.com/watch?v=GLTTI1NFHus",
      "mime": "text/html"
    },
    "semantic": {
      "kind": "embed-media",
      "semanticType": "embedded-video",
      "title": "Provider Native Title"
    },
    "provider": {
      "name": "youtube",
      "confidence": 1,
      "detectionMethod": "url-parser"
    },
    "playback": {
      "strategy": "iframe",
      "component": "iframe",
      "embedUrl": "https://www.youtube.com/embed/GLTTI1NFHus",
      "streamable": false,
      "downloadable": false
    },
    "preview": {
      "thumbnail": {
        "url": "https://i.ytimg.com/vi/GLTTI1NFHus/hqdefault.jpg"
      }
    }
    // diagnostics: omitted (FAST)
    // providerData: omitted (FAST)
  },
  "enrichmentSources": {
    "semantic": "fresh",
    "mediaFormat": "fresh",
    "oembed": "fresh"
  },
  "projection": {
    "profile": "fast",
    "hiddenFields": []       // provider-native preview is NOT hidden
  }
}

FAST Response — Direct Video (Projection-Hidden Preview)

{
  "success": true,
  "responseSource": "fresh",
  "processing": {
    "status": "partial",
    "completion": 0.5,
    "enrichmentsPending": true,
    "completedStages": ["semantic", "mediaFormat"],
    "pendingStages": ["metadata:video", "preview:thumbnail", "preview:blurhash", "preview:palette"]
  },
  "data": {
    "identity": { "url": "https://example.com/video.mp4", "finalUrl": "...", "mime": "video/mp4" },
    "semantic": { "kind": "direct-media", "semanticType": "video" },
    "playback": { "strategy": "native", "component": "video", "streamable": true, "downloadable": true },
    "metadata": { "filename": "video.mp4", "size": { "bytes": 56733664, "formatted": "54.1 MB" } }
    // preview: omitted (projection-hidden for direct media in FAST)
    // diagnostics: omitted (FAST)
  },
  "projection": {
    "profile": "fast",
    "hiddenFields": ["preview"]   // generated preview is hidden
  }
}

STANDARD Profile

Progressive enrichment visibility with async orchestration. Returns partial results immediately for heavy media, with a 202 Accepted status and job reference for background completion.

curl -X POST https://api.urlmediainspector.dev/api/v1/inspect?profile=standard \
  -H "Content-Type: application/json" \
  -d '{"url": "https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4"}'

STANDARD Projection Rules

• data.diagnostics — omitted
• All enrichment data — visible (null if pending, populated if complete)
• Preview enrichments — null-or-populated (progressive null semantics)
• Returns 202 Accepted with job info for heavy media still processing

Progressive Null Semantics

In STANDARD, a null preview field means "this enrichment is supported and registered, but hasn't completed yet." This is distinct from omission, which means "this enrichment is unsupported for this media category."

STANDARD Response — Image (Partial Enrichment)

{
  "success": true,
  "responseSource": "fresh",
  "processing": {
    "status": "partial",
    "completion": 0.5,
    "enrichmentsPending": true,
    "completedStages": ["semantic", "mediaFormat", "metadata:image"],
    "pendingStages": ["preview:thumbnail", "preview:blurhash", "preview:palette"]
  },
  "data": {
    "identity": { "url": "...", "finalUrl": "...", "mime": "image/jpeg" },
    "semantic": { "kind": "direct-media", "semanticType": "image" },
    "metadata": {
      "filename": "image.jpg",
      "size": { "bytes": 2048, "formatted": "2 KB" },
      "image": { "colorSpace": "srgb", "hasAlpha": false }
    },
    "preview": {
      "thumbnail": null,        // supported, pending
      "placeholder": null,      // supported, pending
      "palette": null           // supported, pending
    }
  },
  "projection": {
    "profile": "standard",
    "hiddenFields": []
  }
}

FULL Profile

Deterministic complete enrichment. Blocks synchronously until all enrichments finish. Always returns 200 OK with completion: 1.

curl -X POST https://api.urlmediainspector.dev/api/v1/inspect?profile=full \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.geekygallery.in/cdn/shop/files/god_16.jpg"}'

FULL Projection Rules

• All fields included, including diagnostics with timings
• All enrichments completed synchronously
• completion is always 1
• pendingStages is always []

FULL Response — Image (Complete Enrichment)

{
  "success": true,
  "responseSource": "fresh",
  "cached": false,
  "processing": {
    "status": "complete",
    "completion": 1,
    "enrichmentsPending": false,
    "completedStages": ["semantic", "mediaFormat", "metadata:image", "preview:thumbnail", "preview:blurhash", "preview:palette"],
    "pendingStages": []
  },
  "data": {
    "identity": { "url": "...", "finalUrl": "...", "mime": "image/jpeg" },
    "semantic": { "kind": "direct-media", "semanticType": "image" },
    "metadata": {
      "filename": "god_16.jpg",
      "size": { "bytes": 204800, "formatted": "200 KB" },
      "image": { "colorSpace": "srgb", "hasAlpha": false }
    },
    "preview": {
      "thumbnail": { "url": "/public/thumbnails/generated.jpg", "dimensions": "320x180" },
      "placeholder": { "type": "blurhash", "value": "LEHV6nWB2yk8pyo0adR*.7kCMdnj" },
      "palette": { "dominant": "#112233" },
      "dominantColor": "#112233"
    },
    "diagnostics": {
      "timings": { "total": 1240, "semantic": 12, "mediaFormat": 85, "preview": 890 }
    }
  },
  "enrichmentSources": {
    "semantic": "fresh",
    "mediaFormat": "fresh",
    "metadata:image": "fresh",
    "preview:thumbnail": "fresh",
    "preview:blurhash": "fresh",
    "preview:palette": "fresh"
  },
  "projection": {
    "profile": "full",
    "hiddenFields": []
  }
}

EMBED Profile

Purpose-built for UI integration. Evaluates the URL's embeddability, returning deterministic render strategies, iframe suitability, and verification semantics.

curl -X POST https://api.urlmediainspector.dev/api/v1/inspect?profile=embed \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtu.be/GLTTI1NFHus?si=okdNMy6_p0VSqZJG"}'

EMBED Projection Rules

• Standard metadata, semantics, and previews are omitted
• Only outputs rendering intelligence: embedType, renderability, verification, render, and optionally providerCapabilities
• html is generated on demand via &expand=html

EMBED Response — YouTube

{
  "success": true,
  "profile": "embed",
  "data": {
    "embedType": "embedded-video",
    "mime": "text/html",
    "provider": "youtube",
    "renderability": {
      "native": false,
      "iframe": {
        "supported": "verified",
        "confidence": 1
      },
      "embeddable": {
        "status": "verified"
      }
    },
    "verification": {
      "providerVerified": true,
      "registryVerified": true,
      "networkVerified": true,
      "method": "registry"
    },
    "render": {
      "strategy": "iframe",
      "safeEmbed": true,
      "renderConfidence": {
        "level": "verified",
        "score": 0.95
      },
      "tag": "iframe",
      "attributes": {
        "src": "https://www.youtube.com/embed/GLTTI1NFHus",
        "allowfullscreen": true
      }
    }
  }
}

Processing State Isolation

Critical Invariant

Processing state derives only from the canonical enrichment registry. It must never derive from profile, fields, projection visibility, or formatter decisions.

For the same canonical resource, all profiles report identical processing state:

// YouTube — FAST and FULL both report:
{
  "processing": {
    "status": "complete",
    "completion": 1,
    "enrichmentsPending": false,
    "completedStages": ["semantic", "mediaFormat", "oembed"],
    "pendingStages": []
  }
}
// Only data payload visibility differs between profiles.

Subset Relationship

FAST payload namespaces are always a proper subset of FULL payload namespaces. Every key present in a FAST data block is guaranteed to also exist in the corresponding FULL response.