Annotations JSON API
This document describes the structure of the annotations.json file. To learn more about how annotations work in BuildVu, please read How do annotations work in BuildVu?
We provide a simple implementation for loading and displaying annotations which is used inside the IDRViewer. You are welcome to use this implementation as-provided, for inspiration, or as the basis of your own custom solution.
Basic structure:
{
"pages": [{
"page": 1,
"annotations": [{
"type": "Highlight",
"bounds": [0, 0, 100, 100],
"objref": "255", (optional)
"contents": "contents value", (optional)
"appearance": "1/annots/255.png" (optional)
}
]
}
]
}
Annotation types ("type"): Text, Link, FreeText, Line, Square, Circle, Polygon, PolyLine, Highlight, Underline, Squiggly, StrikeOut, Stamp, Caret, Ink, FileAttachment, Sound, Movie, Widget, Screen, PrinterMark, TrapNet, Watermark, 3D, Projection, RichMedia, Screen, TextLink
Bounds ("bounds"): Supplied in the format [x, y, width, height] with top-left origin.
Object Reference ("objref"): The object reference for the annotation within the PDF file. Object references are not available in two situations:
- In rare cases when the annotations are defined using an inline array.
- When TextLink annotations are generated from links detected from the PDF file.
Contents ("contents"): Typically the plaintext content of popup annotations or a description of the annotation (if provided).
Appearance ("appearance"): A rasterized version of the appearance (AP) stream in the ‘normal’ state (if AP dictionary is provided).
Type Specific Values:
Popup types (Text, Line, Square, Circle, Polygon, PolyLine, Highlight, Underline, Squiggly, StrikeOut, Stamp, Caret, Ink, FileAttachment, Redact, Projection):
{
"type": "Highlight",
"bounds": [0, 0, 100, 100],
"objref": "255", (optional)
"title": "title value", (optional)
"contents": "contents value", (optional)
"appearance": "1/annots/255.png" (optional)
}
Link types (Link, TextLink, Widget):
{
"type": "Link",
"bounds": [0, 0, 100, 100],
"objref": "255", (optional)
"title": "title value", (optional)
"contents": "contents value", (optional)
"action": { }, (optional)
"appearance": "1/annots/255.png" (optional)
}
Action types: URI, GoTo, Named, Sound
Action specific values:
URI:
"action": {
"type": "URI",
"uri": "https://www.example.com"
}
GoTo:
"action": {
"type": "GoTo",
"page": 1
}
Named:
"action": {
"type": "Named",
"name": "NextPage"
}
Name types: NextPage, PrevPage, FirstPage, LastPage
Launch:
"action": {
"type": "Launch",
"target": "executable/or/file/path.pdf"
}
Sound:
"action": {
"type": "Sound",
"sound": "path/to/sound.wav"
}
FileAttachment:
{
"type": "FileAttachment",
"bounds": [0, 0, 100, 100],
"objref": "255", (optional)
"title": "title value", (optional)
"contents": "contents value", (optional)
"attachment": "path/to/file",
"filename": "attachment.pdf",
"appearance": "1/annots/255.png" (optional)
}
RichMedia:
{
"type": "RichMedia",
"bounds": [0, 0, 100, 100],
"objref": "255", (optional)
"contents": "contents value", (optional)
"richmedia": [{
"src": "path/to/media.mp4",
"type": "video/mp4"
}],
"appearance": "1/annots/255.png" (optional)
}
Supported video types: m4v, mov, mp4 (video/mp4)
Supported audio types: mp3 (audio/mpeg)
Screen:
{
"type": "Screen",
"bounds": [0, 0, 100, 100],
"objref": "255", (optional)
"action": {
"type": "Rendition",
"media": {
"src": "path/to/media.mp4",
"type": "video/mp4",
"filename": "named-media.mp4" (optional)
}
},
"appearance": "1/annots/255.png" (optional)
}
Supported media types: mp4 (video/mp4), mp3 (audio/mpeg)
Sound:
{
"type": "Sound",
"bounds": [0, 0, 100, 100],
"objref": "255", (optional)
"title": "title value", (optional)
"contents": "contents value", (optional)
"sound": "path/to/sound.wav",
"appearance": "1/annots/255.png" (optional)
}
Supported media types: wav