๐Ÿค– LLM Guide

A comprehensive reference designed for coding LLMs (GitHub Copilot, ChatGPT, Claude, etc.) to generate correct, accessible PDFs using ObviousPDF. ๐Ÿ“ฅ Download Markdown

๐Ÿค– For AI Coding Assistants

Drop the LLM_GUIDE.md file into your project root or custom instructions to give your AI assistant complete knowledge of the ObviousPDF API, accessibility patterns, and common pitfalls.

What's Covered

๐Ÿ“ Quick Reference Patterns

Minimal PDF, accessible PDF, and the 10-step accessibility checklist โ€” all as copy-paste-ready code blocks.

๐Ÿ”ง 17 Feature Areas

Text, graphics, images, transforms, annotations, forms, bookmarks, page labels, Form XObjects, encryption, signatures, gradients, patterns, layers, associated files, document parts, and colour spaces.

โ™ฟ Complete Accessibility Guide

All required steps for PDF/UA: structure trees, alt text, BBox, reading order, artifacts, language, heading hierarchy, table semantics, link structure, and form tooltips.

โš ๏ธ Common Pitfalls

Known mistakes LLMs make: forgetting DisplayDocTitle, mismatched begin/end calls, missing BBox on figures, unbalanced graphics state, and more.

Sample: Minimal Accessible PDF Pattern

From LLM_GUIDE.md โ€” Accessible Pattern
using ObviousPDF;
using ObviousPDF.Accessibility;

var doc = new PdfDocument();
doc.Language = "en-US";           // Required
doc.Info.Title = "My Document";   // Required
doc.DisplayDocTitle = true;       // Required
doc.PdfUaConformance = PdfUaConformanceLevel.PdfUA1;

var root = doc.EnableTaggedPdf();
var sect = root.AddChild(StructureType.Sect);
var h1 = sect.AddChild(StructureType.H1);
var para = sect.AddChild(StructureType.P);

var page = doc.AddPage();
page.AddTaggedText(h1, "Title", 72, 720,
    new PdfTextOptions {
        Font = StandardFont.HelveticaBold,
        FontSize = 24 });
page.AddTaggedText(para, "Body text.", 72, 690);
page.AddArtifactText("Page 1", 285, 30,
    PdfArtifactType.Pagination);

var report = new PdfAccessibilityChecker().Check(doc);
// report.IsFullyCompliant โ†’ true โœ…

doc.Save("accessible.pdf");

Easy Accessibility โ€” One-Line Pattern (New in v1.2.0)

EnableAccessibility() โ€” Auto-Tags Text & Images
using ObviousPDF;

var doc = new PdfDocument();
doc.EnableAccessibility("en-US", "My Document");
// โ†‘ Sets Language, Title, DisplayDocTitle, PdfUA1, tagged PDF, auto-tagging

var page = doc.AddPage();
page.AddText("Title", 72, 720,              // auto-tagged as <P>
    new PdfTextOptions { Font = StandardFont.HelveticaBold, FontSize = 24 });
page.AddText("Body text.", 72, 690);         // auto-tagged as <P>

var img = PdfImage.FromJpegFile("photo.jpg");
page.AddImage(img, 72, 500, 200, 100,
    "Photo description");                     // auto-tagged as <Figure>

page.AddArtifactText("Page 1", 285, 30,
    PdfArtifactType.Pagination);              // artifact (unchanged)

doc.Save("easy_accessible.pdf");

Use EnableAccessibility() for quick documents. For rich semantics (headings, tables, lists), use manual tagging with EnableTaggedPdf(). Both approaches can be combined.

10-Step Accessibility Checklist

Shortcut: doc.EnableAccessibility("en-US", "Title") handles steps 1โ€“5 automatically. For JSON: "accessible": true. Use manual tagging only when you need rich semantics (headings, tables, lists).

#StepCode
1Set document languagedoc.Language = "en-US"
2Set titledoc.Info.Title = "..."
3Display titledoc.DisplayDocTitle = true
4Enable taggingdoc.EnableTaggedPdf()
5Tag all contentAddTaggedText(), BeginTaggedContent()
6Mark decorative contentBeginArtifact(), AddArtifactText()
7Alt text + BBox on figuresAddChild(Figure, "alt"); fig.BBox = ...
8Heading hierarchy H1โ†’H2โ†’H3No skipping levels
9Table headers with scopeAddHeaderCell(scope, id)
10Validatenew PdfAccessibilityChecker().Check(doc)
โš ๏ธ Disclaimer: The automated accessibility checker and its reports are provided solely to assist in the assessment of document accessibility. They are not a comprehensive accessibility audit. To confirm that WCAG or PDF/UA standards are fully met, human assessment by an accessibility specialist is recommended.

๐Ÿ—‚๏ธ JSON Renderer Guide (ObviousPDF.Json)

Complete reference for AI assistants generating ObviousPDF JSON documents. ๐Ÿ“ฅ JSON Schema (draft-07) ๐Ÿ“‹ Form 1040 Example

What is ObviousPDF.Json?

ObviousPDF.Json is a JSON-to-PDF pipeline. Produce a single JSON document describing the entire PDF โ€” pages, content, fonts, images, forms, accessibility structure, encryption, layers, gradients, digital signatures, bookmarks โ€” and pass it to PdfJsonRenderer to get a valid binary PDF.

Three Rendering Entry Points

C# โ€” PdfJsonRenderer API
using ObviousPDF.Json;

// From a JSON string โ†’ byte[]
byte[] pdf = PdfJsonRenderer.Render(jsonString);

// From a .json file path โ†’ byte[]
byte[] pdf = PdfJsonRenderer.RenderFromFile("document.json");

// Build PdfDocument for further manipulation, then save yourself
PdfDocument doc = PdfJsonRenderer.BuildDocument(jsonString);
doc.Save("output.pdf");

Root Document Structure

The root object has 15 keys. Only pages is required.

KeyTypeRequiredDescription
pagesarrayโœ…Page definitions. At least one required.
coordinateOriginstringNo"bottomLeft" (default, native PDF) or "topLeft" (screen-style, Y increases downward). Overridable per page.
taggedbooleanNotrue to enable tagged PDF. Required for accessibility.
accessiblebooleanNotrue enables full PDF/UA-1: tagged PDF, conformance, display-doc-title, and auto-tagging (text โ†’ <P>, images with altText โ†’ <Figure>). No structureTree or structureId needed. New in v1.2.0.
documentobjectNoInfo, language, pdfVersion, conformance, encryption, signature, linearize, xref/object stream settings.
fontsarrayNoFont library. Referenced via options.fontRef in content.
imagesarrayNoImage library. Referenced via imageRef on image elements.
formXObjectsarrayNoReusable FormXObject templates. Referenced via ref on formXObject elements.
layersarrayNoOCG layer declarations. Referenced via layerRef on layer elements.
shadingsarrayNoAxial/radial gradient declarations. Referenced via shadingId.
patternsarrayNoTiling pattern declarations. Referenced via patternId.
attachmentsarrayNoEmbedded file attachments.
outlinesarrayNoBookmark/outline tree (nestable via children).
pageLabelsarrayNoPage label ranges (e.g. i, ii, iii then 1, 2, 3).
structureTreeobjectNoTagged PDF logical structure root. Required when tagged: true.
roleMappingsarrayNoCustom structure type โ†’ standard type mappings.

Coordinates & Page Sizes

All positions are in points (1 pt = 1/72 inch). Named page sizes:

sizeWidth ร— Height (pt)
"Letter"612 ร— 792
"Legal"612 ร— 1008
"A4"595 ร— 842
"A3"842 ร— 1191
"A5"420 ร— 595
"Tabloid"792 ร— 1224

For custom sizes use "width" and "height" instead of "size". With "topLeft" origin, 1-inch margins = x:72, y:72 from the top-left. With "bottomLeft" origin on Letter, 1-inch top-left margin = x:72, y:720.

Color Formats

A color value is a named string, an RGB object, a grayscale object, or a CMYK object. All numeric components are 0.0 โ€“ 1.0.

Color Examples
"color": "black"                               // named
"color": { "r": 0.2, "g": 0.4, "b": 0.8 }    // DeviceRGB
"color": { "gray": 0.5 }                       // DeviceGray (0=black, 1=white)
"color": { "c": 0, "m": 0.75, "y": 1.0, "k": 0 }  // DeviceCMYK

Named colors: "black" "white" "red" "green" "blue"

Font Library

modeRequired fieldsPDF/UA safe?
"standard"standardFontโŒ Not embedded
"bundled"bundledFontโœ… Embedded, full Unicode
"file"pathโœ… Embedded
"base64"dataโœ… Embedded

Standard font enum values: Helvetica HelveticaBold HelveticaOblique HelveticaBoldOblique Times TimesBold TimesItalic TimesBoldItalic Courier CourierBold CourierOblique CourierBoldOblique Symbol ZapfDingbats

All 27 Content Element Types

Every element in a content array has a required "type" string. All elements additionally accept: structureId (string), artifact (bool), artifactType ("pagination"/"layout"/"page"/"background"), artifactSubtype ("Header"/"Footer").

typeKey Properties
texttext (string), x, y, options
textBlocklines (string[]), x, y, options
imageimageRef or source (inline), x, y, width, height, scaleMode ("exact"/"fit"/"stretch"), altText (string โ€” auto-creates <Figure> with accessible: true)
linex1, y1, x2, y2, drawOptions
rectanglex, y, width, height, mode ("draw"/"fill"/"drawAndFill"), drawOptions
circlecx, cy, r, mode, drawOptions
ellipsecx, cy, rx, ry, mode, drawOptions
polygonpoints ([[x,y],...]), mode, drawOptions
pathoperations (moveTo/lineTo/curveTo/closePath), render ("stroke"/"fill"/"fillAndStroke"), drawOptions
linkuri, x, y, width, height
textAnnotationx, y, contents, color, open
freeTextAnnotationx, y, width, height, contents, options, color
markupAnnotationmarkupType ("highlight"/"underline"/"squiggly"/"strikeOut"), x, y, width, height, color
stampAnnotationicon, x, y, width, height, color
formXObjectref (library id), x, y, width, height
textFieldname, x, y, width, height, tooltip, defaultValue, multiline, password, maxLength, fontSize, readonly, required, anchor
checkboxFieldname, x, y, width, height, tooltip, checked, readonly, required
dropdownFieldname, x, y, width, height, tooltip, options (string[]), selectedIndex, fontSize, readonly, required
listBoxFieldname, x, y, width, height, tooltip, options (string[]), selectedIndex, fontSize, readonly, required
pushButtonFieldname, x, y, width, height, tooltip, label
signatureFieldname, x, y, width, height, tooltip
transformoperation ("translate"/"scale"/"rotate"/"skew"/"matrix"), operation params (tx/ty, sx/sy, angle, angleX/angleY, matrix[6]), content[]
clipshape ("rectangle"/"circle"/"ellipse"), shape params, content[]
layerlayerRef (library id), content[]
shadingshadingId (library id), x, y, width, height
tilingPatternpatternId (library id), x, y, width, height
alphastrokeAlpha (0โ€“1), fillAlpha (0โ€“1), content[]

Text Options (options object)

PropertyType / DefaultDescription
fontRefstringFont library id.
fontSizenumber / 12Size in points.
colorcolorFill color.
leadingnumberLine spacing (baseline to baseline). Default: fontSize ร— 1.2. (Not lineHeight.)
renderingModestring / "fill""fill" ยท "stroke" ยท "fillAndStroke" ยท "invisible"
alignmentstring / "left""left" ยท "center" ยท "right" ยท "justify". Requires width.
widthnumberMax width for wrapping/alignment.
decorationstring[]["underline"] / ["strikeOut"] / ["overline"]
decorationColorcolor
decorationThicknessnumber
superscriptbool / false
subscriptbool / false
outlineColorcolorStroke color for outlined text.
outlineWidthnumberStroke width in points.
backgroundColorcolorHighlight behind text.
shadowColorcolor
shadowOffsetXnumber / 1.0
shadowOffsetYnumber / -1.0
rotationnumber / 0Degrees, counter-clockwise.

Draw Options (drawOptions object)

PropertyType / DefaultDescription
strokeColorcolor
fillColorcolor
lineWidthnumber / 1.0Stroke width in points.
lineCapstring / "butt""butt" / "round" / "projecting"
lineJoinstring / "miter""miter" / "round" / "bevel"
miterLimitnumber / 10.0
dashPatternnumber[]e.g. [5, 3] = 5pt dash, 3pt gap.
dashPhasenumber / 0
strokeAlphanumber / 1.00.0โ€“1.0
fillAlphanumber / 1.00.0โ€“1.0

Tagged PDF in JSON

The structureTree node properties: type (required), id, altText (required for Figure), actualText, language, title, phoneme, phonemeAlphabet ("ipa"/"xSampa"), customType, children[].

Common structure types: Document Part Sect Div P H1โ€“H6 L LI Lbl LBody Table TR TH TD Figure Form Span Link Note

Minimal Accessible JSON Document
{
  "coordinateOrigin": "topLeft",
  "tagged": true,
  "document": {
    "language": "en-US",
    "displayDocTitle": true,
    "info": { "title": "My Report" },
    "conformance": { "pdfUa": "PdfUA1" }
  },
  "fonts": [{ "id": "body", "mode": "bundled", "bundledFont": "NotoSans" }],
  "structureTree": {
    "type": "Document",
    "children": [
      { "type": "H1", "id": "h1" },
      { "type": "P",  "id": "p1" }
    ]
  },
  "pages": [{
    "size": "Letter",
    "content": [
      { "type": "text",      "structureId": "h1", "text": "Report Title",
        "x": 72, "y": 72, "options": { "fontRef": "body", "fontSize": 20 } },
      { "type": "textBlock", "structureId": "p1",
        "lines": ["First paragraph of content."],
        "x": 72, "y": 108, "options": { "fontRef": "body", "fontSize": 11 } },
      { "type": "rectangle", "artifact": true, "artifactType": "layout",
        "x": 72, "y": 770, "width": 468, "height": 1,
        "drawOptions": { "strokeColor": { "gray": 0.7 } } }
    ]
  }]
}
Easy Accessible JSON Document (v1.2.0 โ€” no structureTree needed)
{
  "accessible": true,
  "document": {
    "language": "en-US",
    "info": { "title": "My Report" }
  },
  "fonts": [{ "id": "body", "mode": "bundled", "bundledFont": "NotoSans" }],
  "pages": [{
    "size": "Letter",
    "content": [
      { "type": "text", "text": "Report Title",
        "x": 72, "y": 72, "options": { "fontRef": "body", "fontSize": 20 } },
      { "type": "textBlock",
        "lines": ["First paragraph of content."],
        "x": 72, "y": 108, "options": { "fontRef": "body", "fontSize": 11 } },
      { "type": "rectangle", "artifact": true, "artifactType": "layout",
        "x": 72, "y": 770, "width": 468, "height": 1,
        "drawOptions": { "strokeColor": { "gray": 0.7 } } }
    ]
  }]
}

Encryption

Encrypted, Print-Only PDF
"document": {
  "encryption": {
    "userPassword": "open123",
    "ownerPassword": "admin456",
    "algorithm": "Aes256",
    "allowPrinting": true,
    "allowCopying": false,
    "allowModifying": false,
    "allowAnnotating": false
  }
}

Layers, Gradients & Patterns

Layer + Axial Gradient Pattern
{
  "layers":   [{ "id": "bg", "name": "Background", "visible": true }],
  "shadings": [{
    "id": "grad", "type": "axial",
    "x0": 0, "y0": 0, "x1": 0, "y1": 792,
    "colorStops": [
      { "offset": 0.0, "color": { "r": 0.2, "g": 0.5, "b": 0.9 } },
      { "offset": 1.0, "color": { "r": 0.9, "g": 0.9, "b": 1.0 } }
    ]
  }],
  "patterns": [{
    "id": "dots", "width": 8, "height": 8,
    "content": [{ "type": "circle", "cx": 4, "cy": 4, "r": 1.5,
      "mode": "fill", "drawOptions": { "fillColor": { "gray": 0.8 } } }]
  }],
  "pages": [{
    "size": "Letter",
    "content": [
      { "type": "layer", "layerRef": "bg",
        "content": [
          { "type": "shading", "shadingId": "grad",
            "artifact": true, "x": 0, "y": 0, "width": 612, "height": 792 }
        ]
      },
      { "type": "tilingPattern", "patternId": "dots",
        "artifact": true, "x": 0, "y": 0, "width": 612, "height": 792 }
    ]
  }]
}

Digital Signature

Signed PDF
{
  "document": {
    "signature": {
      "certificatePath": "C:/certs/my-cert.pfx",
      "certificatePassword": "secret",
      "reason": "Document approved",
      "signerName": "Jane Smith",
      "fieldName": "Sig1",
      "pageIndex": 0, "x": 72, "y": 700, "width": 200, "height": 50
    }
  },
  "pages": [{
    "size": "Letter",
    "content": [
      { "type": "signatureField", "name": "Sig1",
        "x": 72, "y": 700, "width": 200, "height": 50,
        "tooltip": "Approval signature" }
    ]
  }]
}

JSON Renderer โ€” Common Pitfalls

ProblemFix
Content at wrong Y positionSet coordinateOrigin once. With "topLeft", Y increases downward. With "bottomLeft" on Letter, top = y:792.
Font not foundVerify options.fontRef exactly matches the font entry id (case-sensitive).
Images not loadingUse absolute paths or "base64" mode for portability across environments.
Tagged PDF accessibility check failsUse "accessible": true for auto-tagging (simplest). Or with manual tagging: every real-content element needs structureId. Every Figure structure node needs altText. Every form field needs tooltip.
options wrong type on dropdownOn dropdownField / listBoxField, options is a string array (the choices), not a text options object.
Signature not applieddocument.signature.fieldName must exactly match the name of a signatureField element on the page.
Line spacing too tight/wideUse leading (not lineHeight) in text options. Default is fontSize ร— 1.2.
Standard fonts fail PDF/UAUse mode: "bundled" or mode: "file". Standard fonts are never embedded.