Media File

1{
2  "schemaVersion": 1,
3  "domain": "media",
4  "entity": "media-file",
5  "displayName": "Media File",
6  "target": {
7    "classification": "native-plus-cms",
8    "nativeEntity": "Media Manager File",
9    "verifiedFqdn": null,
10    "idPolicy": "server-assigned",
11    "crosswalkRequired": true
12  },
13  "sourceAliases": [
14    { "sourceSystem": "wordpress", "sourceEntity": "attachment", "routes": ["/wp/v2/media"], "confidence": "high" },
15    { "sourceSystem": "wix", "sourceEntity": "mediaFile", "routes": ["Media Manager"], "confidence": "high" }
16  ],
17  "preferredWrite": {
18    "surface": "Media Manager Import",
19    "endpoint": "POST /site-media/v1/files/import",
20    "writerId": "importMedia",
21    "verification": "verified-live",
22    "importSafe": true,
23    "bulk": false
24  },
25  "fallbacks": [
26    { "classification": "cms", "when": "Use for attachment parent, captions, external source IDs, or metadata not represented by Media Manager." }
27  ],
28  "reliability": { "status": "partially-reliable", "flags": [] },
29  "pitfalls": [
30    { "code": "async-ready", "severity": "blocker", "summary": "Media import is asynchronous; poll until READY before referencing the file." },
31    { "code": "source-url-access", "severity": "warning", "summary": "Remote source URLs may expire or block hotlinking." }
32  ],
33  "mappingGuidance": ["Import referenced media by default; treat full-library import as explicit opt-in."],
34  "setupRequirements": [],
35  "evidence": [
36    { "type": "repo-research", "path": "research/import-api-suitability/blog-cms-media.md" }
37  ]
38}