JobState

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/majr-app/json-schema/majr-app-job-state-schema.json",
  "title": "JobState",
  "description": "Job status + manifest. For a SUCCEEDED job whose output is in managed temporary storage, ALSO carries the structured, HLS-aware managed result: primaryPlayback (the labeled entry point), an optional poster, and a complete presigned outputs[] inventory. These managed fields are absent when you supplied your own destination.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/encoding-openapi.json#/components/schemas/JobState",
  "type": "object",
  "required": [
    "jobId",
    "status"
  ],
  "properties": {
    "jobId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "QUEUED",
        "PROCESSING",
        "SUCCEEDED",
        "FAILED"
      ]
    },
    "manifest": {
      "$ref": "#/$defs/Manifest"
    },
    "error": {
      "type": [
        "string",
        "null"
      ]
    },
    "primaryPlayback": {
      "$ref": "#/$defs/PrimaryPlayback"
    },
    "poster": {
      "type": "object",
      "required": [
        "path"
      ],
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string"
        }
      },
      "description": "Video poster frame, if produced (managed jobs only)."
    },
    "outputs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ManagedOutput"
      },
      "description": "Complete object inventory for a managed job — download ALL of these, preserving relative paths, then re-host. An HLS master URL is NOT directly streamable: its relative segment/variant references are unsigned."
    },
    "storage": {
      "type": "string",
      "const": "managed-temporary"
    }
  },
  "$defs": {
    "ManagedOutput": {
      "type": "object",
      "required": [
        "path",
        "bytes",
        "url",
        "urlExpiresAt",
        "objectExpiresAt"
      ],
      "description": "One managed object: a presigned GET plus the two distinct expiries.",
      "properties": {
        "path": {
          "type": "string",
          "description": "Full object key (as it appears in the manifest)."
        },
        "bytes": {
          "type": "integer"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Presigned GET — an individual object URL, NOT a streamable HLS package."
        },
        "urlExpiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "When THIS url stops working (~1h). Re-poll GET /v1/jobs/{jobId} for fresh URLs."
        },
        "objectExpiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the object itself is deleted (~72h). Distinct from urlExpiresAt."
        }
      }
    },
    "Manifest": {
      "description": "Shape depends on media type; paths are object keys under destination.prefix.",
      "oneOf": [
        {
          "type": "object",
          "title": "VideoManifest",
          "required": [
            "type",
            "primary",
            "renditions"
          ],
          "properties": {
            "type": {
              "type": "string",
              "const": "video"
            },
            "primary": {
              "type": "object",
              "required": [
                "path",
                "durationSec"
              ],
              "properties": {
                "path": {
                  "type": "string",
                  "description": "HLS master playlist key."
                },
                "durationSec": {
                  "type": "number"
                },
                "aspectRatio": {
                  "type": "number"
                }
              }
            },
            "poster": {
              "type": "object",
              "required": [
                "path"
              ],
              "properties": {
                "path": {
                  "type": "string"
                },
                "aspectRatio": {
                  "type": "number"
                }
              }
            },
            "renditions": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "height",
                  "bandwidth",
                  "path"
                ],
                "properties": {
                  "height": {
                    "type": "integer"
                  },
                  "width": {
                    "type": "integer"
                  },
                  "bandwidth": {
                    "type": "integer"
                  },
                  "path": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        {
          "type": "object",
          "title": "AudioManifest",
          "required": [
            "type",
            "primary"
          ],
          "properties": {
            "type": {
              "type": "string",
              "const": "audio"
            },
            "primary": {
              "type": "object",
              "required": [
                "path",
                "durationSec"
              ],
              "properties": {
                "path": {
                  "type": "string"
                },
                "durationSec": {
                  "type": "number"
                }
              }
            },
            "metadata": {
              "type": [
                "object",
                "null"
              ]
            }
          }
        },
        {
          "type": "object",
          "title": "ImageManifest",
          "required": [
            "type",
            "primary"
          ],
          "properties": {
            "type": {
              "type": "string",
              "const": "image"
            },
            "primary": {
              "type": "object",
              "required": [
                "path"
              ],
              "properties": {
                "path": {
                  "type": "string"
                },
                "aspectRatio": {
                  "type": "number"
                }
              }
            }
          }
        }
      ]
    },
    "PrimaryPlayback": {
      "type": "object",
      "required": [
        "kind",
        "path"
      ],
      "description": "The single entry point to treat as \"the output\": the HLS master playlist (video), the audio file, or the image. `path` matches one entry in outputs[].",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "hls",
            "audio",
            "image"
          ]
        },
        "path": {
          "type": "string"
        }
      }
    }
  }
}