Drawing Operation

Purpose

A Drawing Operation is one mark on a drawing_surface Object's content (see object.md,
Recognized content format: drawing_surface) — the shared, Service-neutral record any Service
uses to describe a freehand mark. It replaces a Service inventing its own private mark format:
Paint uses this structure today; any future sketch, annotation, or whiteboard Object uses the
same one.

A Drawing Operation is not a canonical Action. An Action describes an available interaction; a
Drawing Operation records drawn content.

Ownership

The Canonical Data Model defines the structure of a Drawing Operation. The Service that owns a
drawing_surface Object owns the Resource holding that Object's operations, and is responsible
for validating and storing submitted operations. Storage stores Drawing Operation bytes only as
part of an immutable Resource; it does not interpret them. Runtimes render Drawing Operations
when presenting a drawing_surface Object; they do not own Drawing Operation semantics.

Structure

A Drawing Operation contains:

• id — Identifier for this operation within its Resource's content.
• type — Drawing Operation type.
• created — Timestamp for the operation.
• tool — Tool that produced the operation.
• style — Visual style data required to render the operation.
• geometry — Geometry data required to render the operation.

Initial supported operation type:

stroke

Example stroke:

{
  "id": "drawing.operation:...",
  "type": "stroke",
  "created": "...",
  "tool": "pencil",
  "style": {
    "color": "#000000",
    "width": 4
  },
  "geometry": {
    "points": [
      {"x": 10, "y": 20},
      {"x": 24, "y": 32}
    ]
  }
}

Resource content

A drawing.marks Resource (see resource.md) holds a drawing_surface Object's current
operations:

{
  "width": 1024,
  "height": 768,
  "operations": [
    {
      "id": "drawing.operation:...",
      "type": "stroke",
      "created": "...",
      "tool": "pencil",
      "style": {
        "color": "#000000",
        "width": 4
      },
      "geometry": {
        "points": [
          {"x": 10, "y": 20},
          {"x": 24, "y": 32}
        ]
      }
    }
  ]
}

The drawing.marks Resource is immutable. Adding, undoing, redoing, clearing, or otherwise
changing a drawing surface's marks creates a new drawing.marks Resource; past Resources remain
unchanged. This mirrors immutability elsewhere in the Canonical Data Model (see resource.md).

Submission

A member submits a new Drawing Operation as the drawing_operation-formatted argument of
whichever operation the owning Service's Contract declares for editing that Object (see the
Service Contract Authoring Guide, constraints.format: drawing_operation). The owning Service
appends it to a new drawing.marks Resource and updates the Object's source_resource
reference.

Characteristics

- Drawing Operations are document state, not user-facing Actions.
- Drawing Operations are ordered within their Resource's content.
- Drawing Operations do not contain Storage paths.
- Drawing Operations do not contain runtime HTML.
- Drawing Operations must contain enough data to reproduce the drawing deterministically.
- Drawing Operations are Service-neutral: their structure does not vary by which Service
produced them.