OPF

Search docs

Loading documentation…
    OpenPresentation/opf
    Browse docs
    On this page
    View source

    Image Payload

    An image source and optional image-local text callouts. Other resource kinds use Asset and do not accept callouts.

    Metadata

    Definition
    #/$defs/ImagePayload
    Form
    2 alternative forms (oneOf)
    Source
    spec/schemas/opf.schema.json

    Field index

    This definition uses the forms or value constraints below.

    oneOf 1 · string

    Exact constraints for oneOf 1
    oneOf 1 schema
    {
      "type": "string",
      "examples": [
        "asset:acme-logo",
        "https://cdn.acme.com/image.png",
        "./assets/image.png",
        "data:image/png;base64,..."
      ]
    }

    oneOf 2 · object

    FieldTypeReq.DefaultDescription
    srcstringyes—Image source. Accepts an 'asset:<id>' reference, HTTPS URL, data URI, relative path resolved against the OPF file location, or local filesystem path.
    altstring——Alternative text for the image.
    titlestring——Human-readable asset title for editors and asset pickers.
    descriptionstring——Optional notes about the asset's contents, provenance, or intended use.
    mediaTypestring——Optional MIME media type when it cannot be inferred from src.
    calloutsarray<ref:ImageCallout>——Editable text panels over this image. Coordinates are fractions of its visible frame, measured from the physical top-left even in RTL. Panels are drawn above masks and overlays; overflowing text is reported, never clipped or shrunk below the body role.

    src

    typestringrequiredyesdefault—

    Image source. Accepts an 'asset:<id>' reference, HTTPS URL, data URI, relative path resolved against the OPF file location, or local filesystem path.

    src.json
    {
      "src": "asset:acme-logo"
    }

    alt

    typestringrequirednodefault—

    Alternative text for the image.

    title

    typestringrequirednodefault—

    Human-readable asset title for editors and asset pickers.

    description

    typestringrequirednodefault—

    Optional notes about the asset's contents, provenance, or intended use.

    mediaType

    typestringrequirednodefault—

    Optional MIME media type when it cannot be inferred from src.

    mediaType.json
    {
      "mediaType": "image/svg+xml"
    }

    callouts

    typearray<ref:ImageCallout>requirednodefault—

    Editable text panels over this image. Coordinates are fractions of its visible frame, measured from the physical top-left even in RTL. Panels are drawn above masks and overlays; overflowing text is reported, never clipped or shrunk below the body role.

    Exact constraints for oneOf 2
    oneOf 2 schema
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "src"
      ],
      "properties": {
        "src": {
          "type": "string",
          "description": "Image source. Accepts an 'asset:<id>' reference, HTTPS URL, data URI, relative path resolved against the OPF file location, or local filesystem path.",
          "examples": [
            "asset:acme-logo",
            "./assets/logo.svg",
            "https://cdn.acme.com/logo.png",
            "data:image/svg+xml;base64,..."
          ]
        },
        "alt": {
          "type": "string",
          "description": "Alternative text for the image."
        },
        "title": {
          "type": "string",
          "description": "Human-readable asset title for editors and asset pickers."
        },
        "description": {
          "type": "string",
          "description": "Optional notes about the asset's contents, provenance, or intended use."
        },
        "mediaType": {
          "type": "string",
          "description": "Optional MIME media type when it cannot be inferred from src.",
          "examples": [
            "image/svg+xml",
            "image/png",
            "image/webp"
          ]
        },
        "callouts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ImageCallout"
          },
          "description": "Editable text panels over this image. Coordinates are fractions of its visible frame, measured from the physical top-left even in RTL. Panels are drawn above masks and overlays; overflowing text is reported, never clipped or shrunk below the body role."
        }
      }
    }
    Complete definition constraints
    Schema constraints
    {
      "description": "An image source and optional image-local text callouts. Other resource kinds use Asset and do not accept callouts.",
      "oneOf": [
        {
          "type": "string",
          "examples": [
            "asset:acme-logo",
            "https://cdn.acme.com/image.png",
            "./assets/image.png",
            "data:image/png;base64,..."
          ]
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "src"
          ],
          "properties": {
            "src": {
              "type": "string",
              "description": "Image source. Accepts an 'asset:<id>' reference, HTTPS URL, data URI, relative path resolved against the OPF file location, or local filesystem path.",
              "examples": [
                "asset:acme-logo",
                "./assets/logo.svg",
                "https://cdn.acme.com/logo.png",
                "data:image/svg+xml;base64,..."
              ]
            },
            "alt": {
              "type": "string",
              "description": "Alternative text for the image."
            },
            "title": {
              "type": "string",
              "description": "Human-readable asset title for editors and asset pickers."
            },
            "description": {
              "type": "string",
              "description": "Optional notes about the asset's contents, provenance, or intended use."
            },
            "mediaType": {
              "type": "string",
              "description": "Optional MIME media type when it cannot be inferred from src.",
              "examples": [
                "image/svg+xml",
                "image/png",
                "image/webp"
              ]
            },
            "callouts": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ImageCallout"
              },
              "description": "Editable text panels over this image. Coordinates are fractions of its visible frame, measured from the physical top-left even in RTL. Panels are drawn above masks and overlays; overflowing text is reported, never clipped or shrunk below the body role."
            }
          }
        }
      ]
    }