Understanding the CoCoCo Layout Data Model

This guide is for print industry professionals, especially those in prepress, who are encountering the CoCoCo data model for the first time. We'll translate our digital-first concepts into familiar prepress terms, helping you understand how a job is represented from data to print.

While our system uses a GraphQL API for programmatic access, the focus here is on the what and why of the data structure, not the technical implementation.

1. From Prepress to Pixels: Core Concepts

Think of a CoCoCo Layout as the digital equivalent of an imposition plan or the final, print-ready layout file. It contains everything needed to produce a job: the imposition, artwork files, color information, and finishing details. The model is nested, just like a physical job's components are organized.

Here’s how our digital terms map to physical prepress concepts:

CoCoCo Data Model Term	Prepress Analog	Description
Layout	Imposition Plan / Digital Layout	The top-level container for a single production run's imposition.
LayoutImpositionPlan	Imposition or Gang-Run Plan	Defines how individual products are arranged on press sheets.
LayoutSheet	Press Sheet	A single sheet of substrate that will be printed.
LayoutSheetSide	Front or Back of a Sheet	Represents one side of a press sheet (frontSide, backSide).
LayoutElement	1-Up / Product Position	A single item's position on the ganged sheet (e.g., one business card on a 50-up sheet).
LayoutLayer	Artwork Layer / Separation	An individual layer within a design, like a color separation, a varnish, or a text layer.
LayoutContentObject	Artwork Asset	The actual content, such as a block of text, an image, a barcode, or a die-line. See LayoutContentText, LayoutContentImage, etc.
LayoutColor	Ink & Color Swatches	The list of all colors (spot, process) used in the layout.
revision	Version Number	An internal counter to prevent accidental overwrites. Every change increments it.

The Nested Structure

A Layout organizes these concepts into a clear hierarchy:

Layout (The Imposition)
 ├─ impositionPlan
 │   └─ signatures[*]
 │       └─ sheets[*] (Press Sheets)
 │           ├─ frontSide
 │           │   └─ layoutElements[*] (1-Up Positions)
 │           │       └─ layers[*] (Artwork Layers)
 │           │           └─ contentObjects[*] (Text, Images, etc.)
 │           └─ backSide
 ├─ colorCatalog[*] (Inks)
 ├─ variableFields[*] (Data for VDP)
 └─ separationSets[*] (Color Separations)

2. Common Prepress Tasks & GraphQL Examples

While you may use a graphical interface, these are the underlying API operations that power common prepress tasks.

2.1 Add a New Product to a Ganged Layout

To add a new "1-up" to a press sheet, you use the addLayoutElement mutation. You must specify which sheet and side it belongs to.

GraphQL Mutation: addLayoutElement

{
  "input": {
    "layoutId": "lay_123",
    "revision": 3,
    "sheetId": "sheet_001",
    "side": "FRONT",
    "layoutElement": {
      "id": "element_99",
      "pageNumber": 8,
      "contentBox": { "x": 0, "y": 0, "width": 200, "height": 300, "unit": "pt" },
      "layers": [],
      "layerOrder": []
    }
  }
}

2.2 Swap a Low-Res Image with a High-Res Version

Updating an asset, like an image or graphic, is done with upsertContentObject. You target the specific layer holding the content and provide the new asset details.

GraphQL Mutation: upsertContentObject

{
  "input": {
    "layoutId": "lay_123",
    "revision": 4,
    "sheetId": "sheet_001",
    "side": "FRONT",
    "layoutElementId": "element_99",
    "layerId": "layer_image",
    "contentObject": {
      "type": "Image",
      "id": "img_main",
      "assetId": "asset_new_high_res",
      "fitMode": "Cover",
      "boundingBox": { "x": 0, "y": 0, "width": 200, "height": 300, "unit": "pt" }
    },
    "mode": "REPLACE"
  }
}

2.3 Add a Spot Varnish Layer

Adding a new separation, like a spot varnish or a die-line, involves adding a new Layer to a LayoutElement.

GraphQL Mutation: upsertLayer

2.4 Update Job Notes

Simple changes to metadata, like adding production notes, can be done efficiently with patchLayout. This avoids needing to send the entire layout back and forth.

GraphQL Mutation: patchLayout

{
  "input": {
    "layoutId": "lay_123",
    "revision": 5,
    "operations": [
      { "op": "replace", "path": "/notes", "value": "Customer approved proof on Oct 24." }
    ]
  }
}

3. Best Practices for Prepress Workflows

1. Always Work Against the Latest Revision: Think of the revision number as a version check. Before making a change, ensure you have the latest version of the layout. This prevents two operators from overwriting each other's work.

2. Use the Right Tool for the Job: For small metadata tweaks (like adding notes), use patchLayout. For structural changes (like adding a new product to the sheet), use specific mutations like addLayoutElement.

3. Respect Layout Status: A layout can be in different states (DRAFT, APPROVED, ARCHIVED). You can only edit layouts in DRAFT status. This is a safety measure to prevent changes to approved or archived jobs.

4. Mind Your Units: All measurements require a unit (e.g., pt, in, mm). Always be explicit to avoid scaling errors.

5. Batch Updates Sequentially: If you need to make several changes (e.g., reorder layers and then replace an image), send the commands one after another, using the new revision number returned by the previous command.

4. GraphQL API Reference

For developers building tools on our platform, this section provides a quick reference of the available queries (reading data) and mutations (writing data).

Queries (Reading Data)

GraphQL name	Description
listLayouts	List all layouts (job bags).
getLayout	Fetch a single layout with all its data.
listLayoutElements	Get a flat list of all 1-ups for a layout.
listLayoutLayers	Get a flat list of all layers for a layout.
fetchLayoutColorCatalog	Retrieve the color swatches (ink book) for the layout.
getLayoutVariableFields	Get variable data fields for VDP.
getLayoutSummary	Return high-level counts (sheets, elements, etc.).

Mutations (Writing & Editing Data)

GraphQL name	Description
createLayout	Create a new layout for a component.
replaceLayout	Replace an entire layout document.
approveLayout	Lock a layout and mark it as APPROVED.
archiveLayout	Archive an approved layout.
addLayoutElement	Add a 1-up to a sheet side.
updateLayoutElement	Change an existing 1-up.
removeLayoutElement	Remove a 1-up.
upsertLayer	Add or replace an artwork layer.
upsertContentObject	Add or replace an artwork asset (text, image).
removeContentObject	Delete an artwork asset.
patchLayout	Apply small, targeted changes (e.g., updating notes).

All mutations require the current revision number to ensure data integrity.

5. Getting Started with the API

1. List available layouts to find the id of the job you want to work on.

   query Example {
     listLayouts(limit: 10) {
       id
       componentId
       status
       revision
     }
   }

2. Fetch the full layout document using its id. Note the revision number.

   query LayoutDocument($id: ID!) {
     getLayout(id: $id) {
       id
       revision
       impositionPlan {
         # ... and so on
       }
     }
   }

3. Perform an update using a mutation, providing the revision you just fetched. The operation will return a new revision number. Use this new number for any subsequent edits.

Happy building!